/*
 *    Geotoolkit.org - An Open Source Java GIS Toolkit
 *    http://www.geotoolkit.org
 *
 *    (C) 2005-2012, Open Source Geospatial Foundation (OSGeo)
 *    (C) 2010-2012, Geomatys
 *
 *    This library is free software; you can redistribute it and/or
 *    modify it under the terms of the GNU Lesser General Public
 *    License as published by the Free Software Foundation;
 *    version 2.1 of the License.
 *
 *    This library is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *    Lesser General Public License for more details.
 */
package org.opengis.openoffice;

import com.sun.star.uno.XInterface;
import com.sun.star.beans.XPropertySet;


/**
 * Services from the {@link org.geotoolkit.referencing} package to be exported to
 * <A HREF="http://www.openoffice.org">OpenOffice</A>.
 * <p>
 * This interface is derived from the {@code XReferencing.idl} file using the {@code javamaker}
 * tool provided in OpenOffice SDK, and disassembling the output using the {@code javap} tool
 * provided in Java SDK. This source file exists mostly for javadoc purpose and in order to keep
 * IDE happy. The {@code .class} file compiled from this source file <strong>MUST</strong> be
 * overwritten by the {@code .class} file generated by {@code javamaker}.
 *
 * @author Martin Desruisseaux (IRD, Geomatys)
 * @version 3.20
 *
 * @since 3.20 (derived from 2.2)
 * @module
 */
public interface XReferencing extends XInterface {
    /**
     * Returns the identified object description from an authority code.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @return The object description.
     */
    String getDescription(XPropertySet xOptions, String authorityCode);

    /**
     * Returns the scope for an identified object.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @return The object scope.
     */
    String getScope(XPropertySet xOptions, String authorityCode);

    /**
     * Returns the valid area as a textual description for an identified object.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @return The object valid area.
     */
    String getValidArea(XPropertySet xOptions, String authorityCode);

    /**
     * Returns the valid area as a geographic bounding box for an identified object. This method
     * returns a 2&times;2 matrix. The first row contains the latitude and longitude of upper left
     * corder, and the second row contains the latitude and longitude or bottom right corner. Units
     * are degrees.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @return The object bounding box.
     */
    double[][] getBoundingBox(XPropertySet xOptions, String authorityCode);

    /**
     * Returns the remarks for an identified object.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @return The object remarks.
     */
    String getRemarks(XPropertySet xOptions, String authorityCode);

    /**
     * Returns the axis name for the specified dimension in an identified object.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @param  dimension The dimension (1, 2, ...).
     * @return The name of the requested axis.
     */
    String getAxis(XPropertySet xOptions, String authorityCode, int dimension);

    /**
     * Returns the value for a coordinate reference system parameter.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @param  parameter The parameter name (e.g. "False easting").
     * @return The parameter value.
     */
    Object getParameter(XPropertySet xOptions, String authorityCode, String parameter);

    /**
     * Returns the Well Know Text (WKT) for an identified object.
     *
     * @param  xOptions      Provided by OpenOffice.
     * @param  authorityCode The code allocated by the authority.
     * @param  authority     The authority name for choice of parameter names. Usually "OGC".
     * @return The object WKT.
     */
    String getWKT(XPropertySet xOptions, String authorityCode, Object authority);

    /**
     * Returns the Well Know Text (WKT) of a transformation between two coordinate reference
     * systems.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  sourceCRS The authority code for the source coordinate reference system.
     * @param  targetCRS The authority code for the target coordinate reference system.
     * @param  authority The authority name for choice of parameter names. Usually "OGC".
     * @return The Math Transform WKT.
     */
    String getTransformWKT(XPropertySet xOptions, String sourceCRS, String targetCRS, Object authority);

    /**
     * Returns the accuracy of a transformation between two coordinate reference systems.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  sourceCRS The authority code for the source coordinate reference system.
     * @param  targetCRS The authority code for the target coordinate reference system.
     * @return The operation accuracy.
     */
    double getAccuracy(XPropertySet xOptions, String sourceCRS, String targetCRS);

    /**
     * Transforms coordinates from the specified source CRS to the specified target CRS.
     *
     * @param  xOptions Provided by OpenOffice.
     * @param  coordinates The coordinates to transform.
     * @param  sourceCRS The authority code for the source coordinate reference system.
     * @param  targetCRS The authority code for the target coordinate reference system.
     * @return The transformed coordinates.
     */
    double[][] getTransformedCoordinates(XPropertySet xOptions, double[][] coordinates,
                                         String sourceCRS, String targetCRS);
}
